# Netif : Network interface management

The NetIf is network interface operation library, used to get network interface status and setting related parameters.

User can use the following code to import the NetIf module.

var NetIf = require("netif");

# Support

The following shows NetIf module APIs available for each permissions.

# NetIf Class

# new NetIf(ifname)

• ifname {String} Network interface name.
• Returns: {Object} Network interface object.

Find the specified network interface and return the network interface operation object.

# Example

var eth = new NetIf("en1");

# new NetIf(index)

• index {Integer} Network interface index.
• Returns: {Object} Network interface object.

Find the specified network interface and return the network interface operation object.

# Example

var eth = new NetIf(2);

# NetIf.list()

• Returns: {Array} Network interface list array.

Get all network interfaces of the system. Each item of the return array contains the following elements:

• ifname {String} Network interface name.
• index {Integer} Network interface index.

# Example

var ifList = NetIf.list();

ifList.forEach((item, index) => {
  console.log(item.ifname, "index:", item.index);
});

# NetIf.type(ifname)

• ifname {String} Network interface name.
• Returns: {String} Network interface type.

Get network interface type. Possible types include:

# Example

var ifList = NetIf.list();

ifList.forEach((item, index) => {
  console.log(item.ifname, "type:", NetIf.stats(item.ifname));
});

# NetIf.stats(ifname)

• ifname {String} Network interface name.
• Returns: {Object} Network interface statistics.

The return object includes:

• collisions {Integer} Collisions on csma interfaces.
• baudrate {Integer} Linespeed.
• ipackets {Integer} Packets received on interface.
• ierrors {Integer} Input errors on interface.
• opackets {Integer} Packets sent on interface.
• oerrors {Integer} Output errors on interface.
• ibytes {Integer} Total number of octets received.
• obytes {Integer} Total number of octets sent.
• imcasts {Integer} Packets received via multicast.
• omcasts {Integer} Packets sent via multicast.
• iqdrops {Integer} Dropped on input, this interface.
• noproto {Integer} Destined for unsupported protocol.

Get network interface statistics since system startup.

# NetIf.ifnameList()

• Returns: {Array} Network interface name list array.

Get all network interfaces of the system. Each item of the return array is a network interface name {String}.

# Example

var ifnameList = NetIf.ifnameList();

if (ifnameList.includes("en1")) {
  console.log("Has en1 network interface!");
}

# NetIf.indexToIfname(index)

• index {Integer} Network interface index.
• Returns: {String} Network interface name.

Get the specified index network interface name, if not found return undefined.

# NetIf.ifnameToIndex(ifname)

• ifname {String} Network interface name.
• Returns: {Integer} Network interface index.

Get the specified name network interface index, if not found return zero.

# NetIf Object

# netif.index()

• Returns: {Integer} Network interface index.

Get this network interface index.

# netif.ifname()

• Returns: {String} Network interface name.

Get this network interface name.

# netif.type()

• Returns: {String} Network interface type.

Get network interface type. Possible types include:

# netif.mac()

• Returns: {Object} Network interface MAC address.

Get this network interface MAC address. the return object includes following elements:

• data {Buffer} MAC address binary data.
• mac {String} MAC address string data.

# Example

var eth = new NetIf("en1");

var ifmac = eth.mac();

console.log("en1 mac:", ifmac.mac);

# netif.stats()

• Returns: {Object} Network interface statistics.

The return object includes:

• collisions {Integer} Collisions on csma interfaces.
• baudrate {Integer} Linespeed.
• ipackets {Integer} Packets received on interface.
• ierrors {Integer} Input errors on interface.
• opackets {Integer} Packets sent on interface.
• oerrors {Integer} Output errors on interface.
• ibytes {Integer} Total number of octets received.
• obytes {Integer} Total number of octets sent.
• imcasts {Integer} Packets received via multicast.
• omcasts {Integer} Packets sent via multicast.
• iqdrops {Integer} Dropped on input, this interface.
• noproto {Integer} Destined for unsupported protocol.

Get network interface statistics since system startup.

# Example

var eth = new NetIf("en1");

var stats = eth.stats();

console.log("en1 total output:", stats.obytes);

# netif.addr()

• Returns: {Object} Network interface address.

Get this network interface IPv4 address. the return object includes following elements:

• ipaddr {String} IP address of this network interface.
• netmask {String} Net mask of this network interface.
• gateway {String} Default gateway of this network interface.
• dest {String} Point-to-point network destination address. (Non point-to-point network does not have this member)

# Example

var eth = new NetIf("en1");

var ifaddr = eth.addr();

console.log("en1 addr:", ifaddr.ipaddr);

# netif.addr6(addrIndex)

• addrIndex {Integer} Network interface address index.
• Returns: {Object} Network interface address.

Get this network interface IPv6 address. Each network interface has multiple IPv6 addresses, and the index parameter starts at 0. Each time plus one to traversed until the return value is undefined.

the return object includes following elements:

• ip6addr {String} IP address of this network interface.
• prefix {Integer} Net mask prefix.

# Example

var eth = new NetIf("en1");

for (var i = 0; ; i++) {
  var ifaddr6 = eth.addr6(i);
  if (!ifaddr6) {
    break;
  }
  console.log(ifaddr6);
}

# netif.isUp()

• Returns: {Boolean} Whether the network interface is enabled.

# netif.isLinkup()

• Returns: {Boolean} Whether the network interface is linked up.

# netif.isAutocfg()

• Returns: {Boolean} Whether the network interface is enable IPv6 auto configure.

This feature is available on EdgerOS 1.7.9 and later.

# netif.setAddr(ifaddr)

• ifaddr {Object} Network interface address.
• Returns: {Boolean} Whether the operation was successful.

Set the specified network interface IP address.

The ifaddr must includes following elements:

• ipaddr {String} IP address of this network interface.
• netmask {String} Net mask of this network interface.
• gateway {String} Default gateway of this network interface.
• dest {String} Point-to-point network destination address. (Non point-to-point network ignore this member)

# Example

netif.setAddr({ ipaddr: "192.168.0.8", netmask: "255.255.255.0" });

# netif.setAddr6(ifaddr6)

• ifaddr6 {Object} Network interface address.
• Returns: {Boolean} Whether the operation was successful.

Set the specified network interface IPv6 address.

The ifaddr6 must includes following elements:

• ip6addr {String} IP address of this network interface.
• prefix {Integer} Net mask prefix.

# Example

netif.setAddr6({ ip6addr: "fec0::02", prefix: 64 });

# netif.delAddr6([ifaddr6])

• ifaddr6 {Object} Network interface address. default: delete all IPv6 address except linklocal scope.
• Returns: {Boolean} Whether the operation was successful.

Delete the specified network interface IPv6 address.

# netif.up([dhcp[, dhcp6]])

• dhcp {Boolean} Whether to use DHCP to get the IP address.
• dhcp6 {Boolean} Whether to use DHCPv6 to get the IPv6 address.
• Returns: {Boolean} Whether the operation was successful.

Enable the specified network interface to allow sending and receiving packets.

# Example

netif.up();

# netif.down()

• Returns: {Boolean} Whether the operation was successful.

Disable the specified network interface, not allowed to send and receive data packets.

# netif.dhcp([dhcp[, dhcp6]])

• dhcp {Boolean} Whether DHCP is enabled. Optional.
• dhcp6 {Boolean} Whether DHCPv6 is enabled. Optional.
• Returns: {Object} Current DHCP state.

Get or set network Interface DHCP Status. The configure object contains the following members:

• dhcp {Boolean} Whether DHCP is enabled. Optional.
• dhcp6 {Boolean} Whether DHCPv6 is enabled. Optional.

# Example

// Get
var current = netif.dhcp();
// Set
var current = netif.dhcp(true); // Enable DHCP
var current = netif.dhcp(false, true); // Enable DHCPv6
var current = netif.dhcp(true, true); // Enable DHCP and DHCPv6

# netif.autocfg(enable)

• enable {Boolean} Whether to enable IPv6 auto configure.
• Returns: {Boolean} Whether the setting is successful.

This feature is available on EdgerOS 1.7.9 and later.

# netif.tcpWnd([window])

• window {Integer} TCP window size (8192 ~ 262144).
• Returns: {Integer} TCP window size of the currently specified network interface.

Set or get the TCP window size of the specified network interface.

# netif.ackFreq([freq])

• freq {Integer} TCP acknowledgment packet sending frequency (2 ~ 10).
• Returns: {Integer} TCP acknowledgment packet sending frequency of the currently specified network interface.

Set or get the TCP acknowledgment packet sending frequency of the specified network interface.

# netif.secRegion([newRegion])

• newRegion {Integer} New security region.
• Returns: {Integer} This network interface security region.

Get or set this network interface security region.